home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / PInterfaces / IOIterator.p < prev    next >
Text File  |  1996-05-01  |  4KB  |  145 lines
  1. {
  2.      File:        IOIterator.p
  3.  
  4.      Contains:    xxx put contents here xxx
  5.  
  6.      Version:    Technology:    xxx put the technology version here xxx
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT IOIterator;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __IOITERATOR__}
  28. {$SETC __IOITERATOR__ := 1}
  29.  
  30. {$I+}
  31. {$SETC IOIteratorIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37.  
  38. {$PUSH}
  39. {$ALIGN MAC68K}
  40. {$LibExport+}
  41.  
  42. {$IFC FOR_SYSTEM8_PREEMPTIVE }
  43. {  typedefs }
  44.  
  45. TYPE
  46.     IteratorDescVersion                    = UInt32;
  47. {
  48. ###########################################################
  49.  How to use the IteratorDescVersion
  50. ###########################################################
  51.  Each family will define a k<Family>CurrentIteratorDescVersion constant
  52.  in its *.i file. The client will check the returned IteratorDescVersion
  53.     value against this constant to make sure there's no version mismatch 
  54.      problem.
  55.  Common data structure used by all I/O family iterators
  56. }
  57.     IODeviceRefPtr = ^IODeviceRef;
  58.     IODeviceRef = RECORD
  59.         contents:                ARRAY [0..3] OF UInt32;
  60.     END;
  61.  
  62. {
  63.  a family unique reference number for returned devices.
  64.  this is an opaque field, for now, use the name registry Ref value of the             
  65.     device in question.    
  66.  The IODeviceRef is unique within a family, NOT unique across the entire I/O name space
  67. }
  68.     IOCommonInfoPtr = ^IOCommonInfo;
  69.     IOCommonInfo = RECORD
  70.         ref:                    IODeviceRef;
  71.         versionNumber:            IteratorDescVersion;
  72.     END;
  73.  
  74. {  IteratorDescVersion versionNumber: version number of the family specific IOIteratorData }
  75. {$ENDC}
  76. {
  77. ###########################################################
  78.  How to copy name registry ref --> IODeviceRef
  79. ###########################################################
  80. (
  81.     IOCommonInfo            DeviceData;
  82.     RegEntryRef                *anotherReg, *whichDevice;
  83.     anotherReg = (RegEntryRef *)&DeviceData;
  84.     *anotherReg = *whichDevice;
  85. )
  86. ###########################################################
  87.  How to define a family specific IOIteratorData structure
  88. ###########################################################
  89.  struct <FamilyName>IOIteratorData
  90.  (
  91.       IOCommonInfo     IOCI;    
  92.                     // common data for all families    
  93.         f1,            // Individual family specific data
  94.         f2,
  95.         etc...
  96.  );
  97.  Example 1: (A possible implementation for the SCSI iterator)
  98.     struct SCSIIOIteratorData
  99.  (
  100.       IOCommonInfo     IOCI;    
  101.                     // common data for all families    
  102.         UInt32            BusID;
  103.         UInt32            TargetID;
  104.         UInt32            LUN;
  105.  );
  106. ###########################################################
  107.  How to define a family specific iterator function
  108. ###########################################################
  109. OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  110.             (    ItemCount             requestItemCount,
  111.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),                              
  112.                 ItemCount             *totalItemCountPtr );
  113.                 
  114.  For returning ALL devices that the family have access to
  115.  OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  116.             (    UInt32                familySpecificParam,
  117.                 ItemCount             requestItemCount,
  118.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),
  119.                 ItemCount             *totalItemCountPtr );
  120.                 
  121.  For returning a subset of devices, filtered by some family specific parameters
  122.  EXAMPLES:
  123.  OSStatus SCSIGetDeviceData 
  124.             (    ItemCount             requestItemCount,
  125.                 ItemCount             *totalItemCountPtr,
  126.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  127.  To get all scsi devices
  128.  OSStatus SCSIBusGetDeviceData 
  129.             (    UInt32                BusID,
  130.                 ItemCount             requestItemCount,
  131.                 ItemCount             *totalItemCountPtr,
  132.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  133.  To get all scsi devices that matches the input BusID
  134. }
  135. {$ALIGN RESET}
  136. {$POP}
  137.  
  138. {$SETC UsingIncludes := IOIteratorIncludes}
  139.  
  140. {$ENDC} {__IOITERATOR__}
  141.  
  142. {$IFC NOT UsingIncludes}
  143.  END.
  144. {$ENDC}
  145.